# Settle a headless payment the buyer has approved i

Settle a headless payment the buyer has approved in your own integration. You must call this for any payment session where the settlement value is sync_confirm.

Behavior varies for each payment gateway:
- PayPal confirmation captures the approved order. If you skip it, the buyer's approval expires uncaptured, no payment occurs, and no webhook recovers it.
- Stripe confirmation records payment that has already occurred. If you skip it, the charge.succeeded webhook settles the payment.

The payment.status value has four outcomes:

- paid — The gateway accepted the payment.
- pending — The gateway took the payment but has not settled it (a PayPal PENDING capture, or a Stripe payment method still clearing, such as a bank debit or a redirect method) and the status is Payment Pending. Keep polling the GET /user/invoices/{invoice_id} endpoint.
- declined — The gateway declined the payment method. Present another payment method.
- failed — The attempt did not complete. Try again.

Endpoint: POST /user/invoices/{invoice_id}/payment-session/confirm
Version: 2.1.0

## Path parameters:

  - `invoice_id` (integer, required)
    Invoice ID
    Example: 456

## Request fields (application/json):

  - `provider_reference` (string, required)
    The gateway's identifier for the approved payment:
- For PayPal, this is the onApprove order ID.
- For Stripe, this is the params.paymentIntentId value from the payment session.

WHMCS passes this identifier to the gateway without reading it.
    Example: "pi_3Ph2M2HeadlessIntent"

## Response 200 fields (application/json):

  - `data` (object, required)

  - `data.payment` (object, required)

  - `data.payment.status` (string, required)
    - paid is the only accepted state.
- pending indicates that the payment is still in progress. Continue polling the invoice.
- declined indicates that the payment method was declined.
- failed indicates that the attempt did not complete.
    Enum: "paid", "pending", "declined", "failed"

  - `data.payment.message` (string)
    For declined and failed outcomes, the reason that the payment gateway reported for why payment was declined or failed.
    Example: "INSTRUMENT_DECLINED"

## Response 401 fields (application/json):

  - `message` (string)